Docs: improve docs narrative around "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers".#2227
Open
tk-o wants to merge 21 commits into
Open
Docs: improve docs narrative around "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers".#2227tk-o wants to merge 21 commits into
tk-o wants to merge 21 commits into
Conversation
…-examples-content
New pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins. Update relevant links.
…iter-reader-ensnode-plugins
|
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
Contributor
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (16)
📝 WalkthroughWalkthroughAdds three integration concepts—ENSDb Writers, ENSDb Readers, ENSNode Plugins—by creating dedicated docs pages, updating the Integration Options index and Starlight sidebar, repositioning ENSIndexer as an ENSDb Writer reference implementation, and aligning cross-document links and glossary terms. ChangesENSDb & ENSNode Plugins Architecture
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis documentation-only PR restructures the ENSNode integration docs to clearly explain the "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers" concepts as distinct, decoupled roles. It adds three new integration guide pages, consolidates the old
Confidence Score: 3/5The PR deletes several pages without fully updating the ensdb/index.mdx Quick Start and Documentation Structure sections that reference them, creating multiple 404 links. Three concrete defects were introduced: Quick Start / Documentation Structure link cards in ensdb/index.mdx still point to usage/sdk, usage/sql, usage/index, and integrations/ensnode — all removed or renamed by this PR; the closing ::: fence on line 44 is indented inside a list item and may not be parsed as a closing marker; and a raw HTML tag in the integrations.mdx LinkCard description will render as visible literal text. docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx needs its Quick Start and Documentation Structure link cards updated to reflect deleted/renamed targets, and its admonition closing fence moved to column 0. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
Plugin["ENSNode Plugin\n(abstract spec)"]
Writer["ENSDb Writer\n(implements plugins + metadata writer)"]
ENSIndexer["ENSIndexer\n(reference ENSDb Writer)"]
Envio["Envio\n(in development)"]
Amp["Amp / Edge & Node\n(in discussion)"]
ENSDb[("ENSDb Instance\n(PostgreSQL)")]
Reader["ENSDb Reader\n(reads plugins + metadata)"]
ENSApi["ENSApi\n(reference ENSDb Reader)"]
ensdcli["ensdb-cli\n(in development)"]
ENSEngine["ENSEngine\n(in development)"]
ENSAnalytics["ENSAnalytics\n(coming soon)"]
Plugin -->|implemented by| Writer
Writer --> ENSDb
ENSIndexer -->|is a| Writer
Envio -->|is a| Writer
Amp -->|is a| Writer
ENSDb --> Reader
ENSApi -->|is a| Reader
ensdcli -->|is a| Reader
ENSEngine -->|is a| Reader
ENSAnalytics -->|is a| Reader
Reviews (8): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the documentation narrative around ENSNode Plugins, ENSDb Writers, and ENSDb Readers, positioning ENSIndexer/ENSApi explicitly as reference implementations and adding dedicated integration-option pages to explain the architecture and interoperability model.
Changes:
- Reframes ENSIndexer docs to describe it as an ENSDb Writer reference implementation and clarifies how it implements ENSNode Plugins.
- Expands the ENSDb glossary with definitions for ENSNode Plugin and ENSDb Metadata Writer, and updates related metadata terminology.
- Adds new integration-option pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins, and links them from the integration options index + sidebar.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx | Repositions ENSIndexer as a reference ENSDb Writer and links to glossary terminology. |
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx | Renames/reframes the page to explain ENSNode Plugins and ENSIndexer’s plugin implementation structure. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx | Updates “What you can build” section to point readers to integration inspirations. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx | Adds/updates key definitions (ENSNode Plugin, ENSDb Writer/Reader, Metadata Writer) and metadata terminology. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdx | Adds new top-level integration options for Writers/Readers/Plugins and renumbers subsequent sections. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx | New page describing the ENSNode Plugin specification and listing core/community plugins. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx | Adds paragraph explaining ENSDb’s metadata spec and links to Writers/Readers pages. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx | New page describing the ENSDb Writer spec and reference/partner implementations. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx | New page describing the ENSDb Reader spec and reference reader apps. |
| docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/services.ts | Renames the ENSIndexer contributing sidebar item to “ENSNode Plugins”. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts | Adds sidebar entries for Writers/Readers/Plugins integration-option pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx`:
- Around line 44-47: The LinkCard for "Learn more about ENSAnalytics (coming
soon)" is missing the required href prop; update the LinkCard component in
ensdb-readers.mdx to include an href (e.g., a placeholder route like
"/ensanalytics" or a temporary external URL) so the
`@astrojs/starlight/components` LinkCard receives a valid href, keeping the title
"ENSAnalytics" and description unchanged; ensure the href is a string literal
and points to the placeholder until the real route exists.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx`:
- Line 11: The bullet under "writer responsibilities" contains a malformed
fragment "How to process onchain data into (including transforming raw onchain
data into a desired internal data model)"; replace it with a complete,
grammatical sentence such as "How to process on‑chain data, including
transforming raw on‑chain data into a desired internal data model" so the
responsibility reads clearly—update the writer responsibilities bullet in the
ENSDB writers section to use that full sentence.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx`:
- Line 14: Update the interoperability phrasing in the sentence referencing the
"ENSDb standard" so that it reads "...supports decoupling and interop with any
EnsDbReader implementation." Locate the sentence that mentions "EnsDbWriters",
"ENSDb instance" and "EnsDbReaders" and replace the fragment "interop with any
of EnsDbReaders" with "interop with any EnsDbReader implementation" to tighten
grammar and clarity.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx`:
- Line 23: In the paragraph starting with "ENSNode Plugins are the key
architectural piece..." replace both occurrences of the phrase "standards
compliant" with the hyphenated form "standards-compliant" to make the compound
adjective consistent and improve readability; update the two instances that
describe an ENSDb Writer producing a "standards-compliant ENSDb" and an ENSDb
Reader being "standards-compliant" so both are hyphenated.
In `@docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx`:
- Line 70: Update the glossary sentence for ENSDb Reader to avoid "sole ENSDb
Writer" — in the ENSDb Reader definition replace "the sole [ENSDb
Writer](`#ensdb-writer`)" with either "an [ENSDb Writer](`#ensdb-writer`)" or "the
configured [ENSDb Writer](`#ensdb-writer`) for the reader context" so it aligns
with the multi-tenant model; edit the sentence in the ENSDb Reader paragraph in
glossary.mdx (the line containing "Any application that reads ENS data...")
accordingly.
- Around line 64-65: Update the broken self-link and grammar in the ENSDb
glossary sentence: change the relative link
"docs/services/ensdb/concepts/glossary#ensnode-metadata-table" to an absolute
path by adding a leading "/" (i.e.
"/docs/services/ensdb/concepts/glossary#ensnode-metadata-table") and fix the
agreement typo by replacing "instance that have" with "instance that has" in the
same paragraph referring to ENSIndexer and the ENSNode Metadata Table.
In
`@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx`:
- Around line 11-13: Replace the inconsistent glossary terms in this document:
change occurrences of `EnsDbWriter`, `EnsDbWriters`, and `EnsDbReaders` to the
canonical capitalized forms `ENSDb Writer`, `ENSDb Writers`, and `ENSDb Readers`
respectively so they match the rest of the docs; update both the inline mentions
and any link text (e.g., the two instances in the second paragraph and the first
sentence) while preserving existing links/URLs and surrounding punctuation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 17b3bbe3-d245-47a9-85d0-e73061144aee
📒 Files selected for processing (14)
docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.tsdocs/ensnode.io/config/integrations/starlight/sidebar-topics/services.tsdocs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx`:
- Line 3: The frontmatter description contains a typo: "How to build custom APIs
and under services on top of ENSDb, using the ENSDb Reader standard."; update
the description string in the document's frontmatter to read "How to build
custom APIs and other services on top of ENSDb, using the ENSDb Reader
standard." so the phrase "under services" is replaced with "other services"
(edit the description field in the frontmatter).
- Line 16: In the ENSDb readers doc sentence that currently reads "APIs for
various queries related to the the metadata stored in ENSDb..." remove the
duplicated article so it reads "related to the metadata stored in ENSDb"; update
the string in the ENSDb readers content (look for the exact sentence "APIs for
various queries related to the the metadata stored in ENSDb") to fix the typo
and keep the rest of the paragraph unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: e5927c44-904c-4d03-bfb5-07a2a068ac45
📒 Files selected for processing (10)
docs/ensnode.io/config/integrations/starlight/sidebar-topics/services.tsdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx
💤 Files with no reviewable changes (1)
- docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx (1)
29-29:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix punctuation and sentence flow in Line 29.
There is an extra period after “environment variable” and an unnecessary comma in “developed, and tested”.
Proposed fix
-Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed, and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable.. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: +Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx` at line 29, Fix the punctuation and flow in the sentence that mentions the PLUGINS environment variable: remove the extra period after "environment variable", delete the unnecessary comma in "developed, and tested" (change to "developed and tested"), and adjust spacing so the sentence reads smoothly (e.g., end with a single period). Locate the sentence that references the "PLUGINS" environment variable and update it accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In
`@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx`:
- Line 29: Fix the punctuation and flow in the sentence that mentions the
PLUGINS environment variable: remove the extra period after "environment
variable", delete the unnecessary comma in "developed, and tested" (change to
"developed and tested"), and adjust spacing so the sentence reads smoothly
(e.g., end with a single period). Locate the sentence that references the
"PLUGINS" environment variable and update it accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8682a2e3-0fae-475e-b6cc-606695071e94
📒 Files selected for processing (9)
docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx
…iter-reader-ensnode-plugins
|
|
||
| ## Plugin implementation structure | ||
|
|
||
| Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed, and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable.. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: |
Contributor
There was a problem hiding this comment.
Suggested change
| Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed, and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable.. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: | |
| Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module with a modular structure that can be developed and tested independently, while all plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: |
Sentence contains grammar errors (unnecessary comma, double period) and unclear phrasing in plugin documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is a followup to PR #2199, and PR #2202, and addresses the "Big Feedback" (point 11. and 17.) section the doc discussed in this thread, as well as the feedback shared in this thread.